Loading...
 

MorphIT 4.0.0 Configuration

MorphIT 4.0.0 Configuration

The configuration of the server is described here. This page describes the differences between the configuration of version 4.0.0 and its predecessors and the migration.

With version 4.0.0 of MorphIT the folder structure, the configuration and the start scripts have been revised. These adjustments should enable the following:

  • Easier administration of MorphIT installations through central morphit script
  • Easier configuration through central configuration of all components /config/config.js & /config/custom/config.js
  • Easier installation due to central node modules in /node_modules in contrast to node modules for each individual component
  • Start of several MorphIT projects from one MorphIT installation by configuration files (morphit-configurations). This also gives the possibility to store the configuration files outside the MorphIT directory and transfer MorphIT with a new version without losing the configurations or using the same configurations for different versions.
  • There are common modules that can be used by all components (/utility)

This change means that the configuration files must be revised when changing to version 4.0.0. In addition, the services must be set up again.

Migration steps

For the migration from an earlier version to 4.0.0 there is a migration script which translates the configurations. You should proceed as follows for the migration.

  1. Place new MorphIT directory (/new) next to the old directory (/old), do not delete the old directory yet. The old directory must not be simply overwritten, otherwise the automatic migration will not work.
  2. Run /alt/start_maintenance.bat (Only necessary if the server is running)
  3. Run /alt/morphit/uninstall_service.bat with administrator rights (Only necessary if the server was installed as a service)
  4. Run /alt/launcher/uninstall_service.bat with administrator rights (Only necessary if the launcher was installed as a service)
  5. Run /neu/morphit.bat migrate ../alt in the CMD to update the configuration to the new format. This automated conversion unfortunately loses all comments within the configuration files. The /config/custom/config.js can also be created manually according to the description here.
  6. Now you can delete /old and rename /new as desired.
  7. Start /new/morphit.bat install server with administrator rights (If the server should be started as a service)
  8. Start /new/morphit.bat install launcher with administrator rights (If the launcher should be started as a service)

Folder structure

Changes to the previous structure are highlighted in bold.

/

morphite.bat

The morphit.bat represents the central MorphIT administration script, which replaces all previous scripts from the MorphIT directory. The old scripts are now stored in a slightly modified form in /scripts, but the scripts should not be started there directly, because morphit.bat performs important configuration steps before the scripts are called. However, each script has been reworked to output how the script can be called via morphit.bat instead.

The morphit.bat can be started interactively (without parameters), then the user is navigated through menus that let him select configuration and action to be performed with a short description or one starts the morphit.bat with command line arguments that specify configuration, action and target. This way you can also create shortcuts that perform certain actions.

Call Description
morphite MorphIT asks for the configuration, action and target (intercative start)
morphite CONFIGURATION MorphIT loads the specified configuration and asks for the action to be performed and optionally the target.
morphite CONFIGURATION ACTION MorphIT loads the configuration and starts the action. If the action requires a target (e.g. install, start, uninstall), MorphIT interactively asks for it.
morphite CONFIGURATION ACTION TARGET ... MorphIT loads the configuration and starts the action with the specified target. Optionally, command line arguments can follow, which are passed to the action to be started.
morphite ACTION MorphIT loads the default.bat as configuration and starts the action. If the action requires a target (e.g. install, start, uninstall), MorphIT interactively asks for it.
morphite action target ... MorphIT loads the default.bat as configuration and starts the action with the specified target. Optionally, command line arguments can follow, which are passed to the action to be started.

Valid actions

Action Description
install Installs the server or launcher service
start Starts the server, the launcher, the console or the maintenance mode.
uninstall Uninstalls a previously installed service
update Updates/Installs the node modules
shutdown Terminates the Server, Launcher and ClassiX processes hard. If possible the maintenance mode should be used instead.

The morphit.bat first loads a MorphIT configuration, which is defined as a .bat file within morphit-configurations. If only one project is started using this MorphIT installation, then simply load the empty configuration (default.bat) and make the necessary configuration in /config/custom/config.js.

Then, depending on the selected action and the target, the corresponding script is started from /scripts.
Example: morphit start server first loads the default configuration and then calls /scripts/start_server.bat.

Warning: When using CLINK, CTRL+C to abort the MorphIT script in interactive mode does not work correctly at command prompts. The script will then repeat the question or accept empty input instead of exiting. This is a problem with CLINK itself and does not occur when using Windows CMD.

morphite configurations

The morphit-configurations-directory(s) are searched for configurations by the MorphIT-script at startup. Ascending to the root directory (C:\, Y:\), the script searches all morphit-configurations-directories for .bat-files (.cmd-files are read over), which are interpreted as configurations.

This way configurations can be stored outside the MorphIT directory and will not be overwritten if the MorphIT directory is changed. If there are several configurations with the same name in different directories, then all configuration files are loaded, whereby the files closer to the root directory are loaded first and the values set there are overwritten by configurations closer to the MorphIT directory.

Semantics

A MorphIT configuration can influence the behavior of the MorphIT script and defines the configuration files that are loaded by the server, launcher and admin console at startup and can define additional startup parameters. The basic idea of the configurations is to be able to start different ClassiX projects with one MorphIT installation.

The environment variables that can be used and the variables to be set are described in the following tables

Available variables

Variable Meaning
COMMON_CONFIG The path to the common.cmd script, which can be called to create a project configuration with minimal effort. Example: CALL "%COMMON_CONFIG%" Evaluation
MORPHIT_DIR The directory where morphit.bat is located
SCRIPT_DIR The path to the /scripts directory

Settable variables

Variable Meaning
Installation
AUTO If this variable is set to YES, then queries are skipped during installation/uninstallation of services.
LOG_IR If this variable is set, one of the services installed via morphit install will write its logs to the specified directory. The directory is created as required. In this case morphit install will not ask for the log directory during installation.
SERVICE_SUFFIX The suffix used to distinguish the services of multiple MorphIT projects. The project name, for example, can be used for this.
Start
CONFIG_FILES A semicolon-separated list of paths to config.js files to be loaded when the Server, Launcher and Admin Console are started. The files are loaded before /config/custom/config.js and have the same format and should be used to assign separate ports for each MorphIT project and to customize the Launcher's startup options. The common.cmd sets this path to CX_ROOTDIR\system\morphitConfig.js so that project-specific options such as the design can be set there.
CONSOLE_PARAMS Command line arguments to be passed to the Admin Console at each startup.
LAUNCHER_PARAMS Command line arguments to be passed to the launcher at each startup.
NODE_PARAMS Command line arguments to be passed to NodeJS at the start of each component. These options are not interesting for normal operation and are used for debugging the application (see: /morphit-configurations/debug.bat)
SERVER_PARAMS Command line arguments to be passed to the Server Console at each startup.
UPDATE_ON_EACH_START This value can be set to YES to force an update of the node modules each time a component is started. This can slow down the startup significantly and an update of the node modules is only necessary when MorphIT is exchanged and can also be done manually via morphit update. In addition, independently of UPDATE_ON_EACH_START, a morphit update is always executed before morphit start services to ensure that the node modules are up-to-date before the MorphIT services are started.

Alternatively, these environment variables can be set in a calling batch script if no configuration is to be defined. Then the above mentioned available variables are of course not yet available and you should start the default configuration, because it does not overwrite any values.

config.js

Since the launcher, server and admin console must agree on the same ports, endpoints and SSL options in their configurations, the /server/config.js has been moved to /config/config.js and expanded by a few fields so that all components can load their configuration from this one configuration file.
The following changes have been made to the configuration:
  • File paths specified as relative paths are no longer relative to the /server directory, but to the MorphIT main directory.
  • The hostname/IP under which the launcher can reach the server must be specified in the host field, if the launcher is running on a different machine.
  • maintenance from /admin_console/config/config.js is now located under ws.admin.maintenance in /config/config.js
  • The launcher configuration from /launcher/config/launcher.js is now under ws.launcher
  • The start configuration from /launcher/config/launch.js is now located at ws.launcher.launch

The rest of the structure was not changed.

After the /config/config.js is loaded, all configuration files set in the CONFIG_FILES variable by the configuration script are loaded. Then the /config/custom/config.js is loaded (if available) and finally (if specified) options are set (if any), which are set via additional start parameters (example: morphit start server --custom.port 80). Files loaded later will overwrite the values of previously set files.